'\" t
.TH mget 1 "14 May 2008" "Code Manager II"

.SH NAME
mget \- Retrieve file versions

.SH SYNOPSIS
mget [\fB--version\fP \fIX\fP] [\fB--indir\fP \fIdir\fP] [\fB--verbose\fP]
     [\fB--print\fP] [\fB--force-write\fP] file ...

.SH DESCRIPTION
The \fImget(1)\fP utility is used to retrieve particular versions of a file
from the version control repository. By default it will retrieve the latest
checked in version, though this can be changed via the command line arguments.

All files retrieved are retrieved in a read-only manner, and are, by default,
copied to the current working directory. Any number of files in the current
directory can be specified, though pattern matching works only compared to files
in the existing directory, not in the equivalent code repository.

.SH ARGUMENTS
.TP 8
.B --verbose
Show more information regarding the code retrieval process process. Particularly
useful if the results are not as you expect - since the version specification
supported can be quite complex.
.TP
.B --version
Indicates the version to retrieve. Only one version can be specified, though it
can be as a digital signature, a local repository version, or even a TAG: or
DATE: specification - see \fBVERSION SPECIFICATION\fP below for details.
.TP
.B --indir
Extract the files in question to the specified directory rather than the
current working directory.
.TP
.B --print
Useful for scripts - the contents of the retrieved file[s] are written to
standard output rather than to the file system.
.TP
.B --force-write
This option must be used if attempting to retrieve a version of a file
into the working directory of the project in question where the contents
of the current contents of the file [if it exists] are unknown to the
version control system. Without this option it will fail since it will
replace the file and the current contents will essentially be 'lost'.

.SH VERSION SPECIFICATION
If a version needs to be specified it can be done so in a number
of ways including:

.TP 4
.B * Local version numbers
The local version number can be specified directly or 
following the 'LOCAL:' designation. For example all of the below
are local version [depending on the back-end repository type]:

.TS
l.
1
1.21
121
LOCAL:1.2
LOCAL:434
.TE

.TP
.B * SHA1 digital signature
This should be the complete SHA1 reference either directly 
or following the 'SHA1:' designation. Hence the following two
examples are identical:

.TS
l.
7c91fd774dd742ea7921da3cd32f1ecb898ccd89
SHA1:7c91fd774dd742ea7921da3cd32f1ecb898ccd89
.TE

.TP
.B * Tag Reference
To get a version of a file for a specified tag the format
on the command line should be:

.TS
l.
TAG:nameoftag
.TE

.TP
.B * Date Specification
A date can be specified in the format 'DATE:YYYYMMDDHHMMSS' - 
all components from the left are optional apart from
the year. This will match against the oldest version following
that date. Examples are:

.TS
l l.
DATE:2005	Match the oldest file since 2005/01/01 00:00:00
DATE:200510	Match the oldest file since 2005/10/01 00:00:00
DATE:2006012310	Match the oldest file since 2006/01/23 10:00:00
.TE

.SH EXIT CODES
The \fImget(1)\fP follows UNIX standard practise:

.TP 4
.B 0
The specified files have all been successfully extracted.
.TP
.B >0
The command encountered an unexpected error - not all files
requested could be extracted.

.SH AUTHOR
The \fBCode Manager II\fP tool set was written by Simon Edwards, Proprius Consulting Ltd, (\fBwww.proprius.co.uk\fP).

.SH SEE ALSO
.BR cm2(1),
.BR cm2_mdiff(1).
.BR cm2_mci(1),
.BR cm2_mco(1),
.BR cm2_minfo(1).

.SH AVAILABILITY
This utility was specifically written under the GNU GPL license and as required
by such software comes with \fIno warranty or guarantee of any kind\fP.

